Element (from Node)

The base element.

Options

  • fg, bg, bold, underline - Attributes.

  • style - May contain attributes in the format of:

    {
    fg: 'blue',
    bg: 'black',
    border: {
    fg: 'blue'
    },
    scrollbar: {
    bg: 'blue'
    },
    focus: {
    bg: 'red'
    },
    hover: {
    bg: 'red'
    }
}

  • border - Border object, see below.

  • content - Element's text content.
  • clickable - Element is clickable.
  • input, keyable - Element is focusable and can receive key input.
  • focused - Element is focused.
  • hidden - Whether the element is hidden.
  • label - A simple text label for the element.
  • hoverText - A floating text label for the element which appears on mouseover.
  • align - Text alignment: left, center, or right.
  • valign - Vertical text alignment: top, middle, or bottom.
  • shrink - Shrink/flex/grow to content and child elements. Width/height during render.
  • padding - Amount of padding on the inside of the element. Can be a number or an object containing the properties: left, right, top, and bottom.
  • width, height - Width/height of the element, can be a number, percentage (0-100%), or keyword (half or shrink). Percentages can also have offsets (50%+1, 50%-1).
  • left, right, top, bottom - Offsets of the element relative to its parent. Can be a number, percentage (0-100%), or keyword (center). right and bottom do not accept keywords. Percentages can also have offsets (50%+1, 50%-1).
  • position - Can contain the above options.
  • scrollable - Whether the element is scrollable or not.
  • ch - Background character (default is whitespace ).
  • draggable - Allow the element to be dragged with the mouse.
  • shadow - Draw a translucent offset shadow behind the element.

Properties

  • Inherits all from Node.
  • name - Name of the element. Useful for form submission.
  • border - Border object.
  • type - Type of border (line or bg). bg by default.
  • ch - Character to use if bg type, default is space.
  • bg, fg - Border foreground and background, must be numbers (-1 for default).
  • bold, underline - Border attributes.
  • style - Contains attributes (e.g. fg/bg/underline). See above.
  • position - Raw width, height, and offsets.
  • content - Raw text content.
  • hidden - Whether the element is hidden or not.
  • visible - Whether the element is visible or not.
  • detached - Whether the element is attached to a screen in its ancestry somewhere.
  • fg, bg - Foreground and background, must be numbers (-1 for default).
  • bold, underline - Attributes.
  • width - Calculated width.
  • height - Calculated height.
  • left - Calculated relative left offset.
  • right - Calculated relative right offset.
  • top - Calculated relative top offset.
  • bottom - Calculated relative bottom offset.
  • aleft - Calculated absolute left offset.
  • aright - Calculated absolute right offset.
  • atop - Calculated absolute top offset.
  • abottom - Calculated absolute bottom offset.
  • draggable - Whether the element is draggable. Set to true to allow dragging.

Events

  • Inherits all from Node.
  • blur, focus - Received when an element is focused or unfocused.
  • mouse - Received on mouse events for this element.
  • mousedown, mouseup - Mouse button was pressed or released.
  • wheeldown, wheelup - Wheel was scrolled down or up.
  • mouseover, mouseout - Element was hovered or unhovered.
  • mousemove - Mouse was moved somewhere on this element.
  • click - Element was clicked (slightly smarter than mouseup).
  • keypress - Received on key events for this element.
  • move - Received when the element is moved.
  • resize - Received when the element is resized.
  • key [name] - Received on key event for [name].
  • prerender - Received before a call to render.
  • render - Received after a call to render.
  • hide - Received when element becomes hidden.
  • show - Received when element is shown.
  • destroy - Received when element is destroyed.

Methods

  • Inherits all from Node.
  • Note: If the scrollable option is enabled, Element inherits all methods from ScrollableBox.
  • render() - Write content and children to the screen buffer.
  • hide() - Hide element.
  • show() - Show element.
  • toggle() - Toggle hidden/shown.
  • focus() - Focus element.
  • key(name, listener) - Bind a keypress listener for a specific key.
  • onceKey(name, listener) - Bind a keypress listener for a specific key once.
  • unkey(name, listener) - Remove a keypress listener for a specific key.
  • onScreenEvent(type, handler) - Same asel.on('screen', ...) except this will automatically keep track of which listeners are bound to the screen object. For use with removeScreenEvent(), free(), and destroy().
  • removeScreenEvent(type, handler) - Same asel.removeListener('screen', ...) except this will automatically keep track of which listeners are bound to the screen object. For use with onScreenEvent(), free(), and destroy().
  • free() - Free up the element. Automatically unbind all events that may have been bound to the screen object. This prevents memory leaks. For use with onScreenEvent(), removeScreenEvent(), and destroy().
  • destroy() - Same as the detach() method, except this will automatically call free() and unbind any screen events to prevent memory leaks. for use with onScreenEvent(), removeScreenEvent(), and free().
  • setIndex(z) - Set the z-index of the element (changes rendering order).
  • setFront() - Put the element in front of its siblings.
  • setBack() - Put the element in back of its siblings.
  • setLabel(text/options) - Set the label text for the top-left corner. Example options: {text:'foo',side:'left'}
  • removeLabel() - Remove the label completely.
  • setHover(text/options) - Set a hover text box to follow the cursor. Similar to the "title" DOM attribute in the browser. Example options: {text:'foo'}
  • removeHover() - Remove the hover label completely.
  • enableMouse() - Enable mouse events for the element (automatically called when a form of on('mouse') is bound).
  • enableKeys() - Enable keypress events for the element (automatically called when a form of on('keypress') is bound).
  • enableInput() - Enable key and mouse events. Calls bot enableMouse and enableKeys.
  • enableDrag() - Enable dragging of the element.
  • disableDrag() - Disable dragging of the element.
  • screenshot([xi, xl, yi, yl]) - Take an SGR screenshot of the element within the region. Returns a string containing only characters and SGR codes. Can be displayed by simply echoing it in a terminal.

Content Methods

Methods for dealing with text content, line by line. Useful for writing a text editor, irc client, etc.

Note: All of these methods deal with pre-aligned, pre-wrapped text. If you use deleteTop() on a box with a wrapped line at the top, it may remove 3-4 "real" lines (rows) depending on how long the original line was.

The lines parameter can be a string or an array of strings. The line parameter must be a string.

  • setContent(text) - Set the content. Note: When text is input, it will be stripped of all non-SGR escape codes, tabs will be replaced with 8 spaces, and tags will be replaced with SGR codes (if enabled).
  • getContent() - Return content, slightly different from el.content. Assume the above formatting.
  • setText(text) - Similar to setContent, but ignore tags and remove escape codes.
  • getText() - Similar to getContent, but return content with tags and escape codes removed.
  • insertLine(i, lines) - Insert a line into the box's content.
  • deleteLine(i) - Delete a line from the box's content.
  • getLine(i) - Get a line from the box's content.
  • getBaseLine(i) - Get a line from the box's content from the visible top.
  • setLine(i, line) - Set a line in the box's content.
  • setBaseLine(i, line) - Set a line in the box's content from the visible top.
  • clearLine(i) - Clear a line from the box's content.
  • clearBaseLine(i) - Clear a line from the box's content from the visible top.
  • insertTop(lines) - Insert a line at the top of the box.
  • insertBottom(lines) - Insert a line at the bottom of the box.
  • deleteTop() - Delete a line at the top of the box.
  • deleteBottom() - Delete a line at the bottom of the box.
  • unshiftLine(lines) - Unshift a line onto the top of the content.
  • shiftLine(i) - Shift a line off the top of the content.
  • pushLine(lines) - Push a line onto the bottom of the content.
  • popLine(i) - Pop a line off the bottom of the content.
  • getLines() - An array containing the content lines.
  • getScreenLines() - An array containing the lines as they are displayed on the screen.
  • strWidth(text) - Get a string's displayed width, taking into account double-width, surrogate pairs, combining characters, tags, and SGR escape codes.
Last update: February 22, 2020